home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / System / ReqToolsLib / Source / reqtools / rtfilerequesta.c < prev    next >
Encoding:
C/C++ Source or Header  |  2001-07-02  |  9.8 KB  |  284 lines
  1.  
  2. /*
  3.     (C) 1999 - 2000 AROS - The Amiga Research OS
  4.     $Id: rtfilerequesta.c,v 1.3 2000/11/26 16:53:48 stegerg Exp $
  5.  
  6.     Desc:
  7.     Lang: English
  8. */
  9.  
  10. #include <exec/types.h>
  11. #include <proto/exec.h>
  12. #include <proto/reqtools.h>
  13. #include <proto/intuition.h>
  14. #include <exec/libraries.h>
  15. #include <exec/memory.h>
  16. #include <aros/libcall.h>
  17.  
  18. #include "reqtools_intern.h"
  19.  
  20. /*****************************************************************************
  21.  
  22.     NAME */
  23.  
  24.     AROS_LH4(APTR, rtFileRequestA,
  25.  
  26. /*  SYNOPSIS */
  27.  
  28.     AROS_LHA(struct rtFileRequester *, filereq, A1),
  29.     AROS_LHA(char *, file, A2),
  30.     AROS_LHA(char *, title, A3),
  31.     AROS_LHA(struct TagItem *, taglist, A0),
  32.  
  33. /*  LOCATION */
  34.  
  35.     struct ReqToolsBase *, ReqToolsBase, 9, ReqTools)
  36.  
  37. /*  FUNCTION
  38.     Get a directory and filename(s), or just a directory from the user.
  39.  
  40.     'filename' should point to an array of at least 108 chars. The
  41.     filename already in 'filename' will be displayed in the requester
  42.     when it comes up. When the requester returns 'filename' will
  43.     probably have changed.
  44.  
  45.     Using certain tags may result in the calling of a caller-supplied
  46.     hook.
  47.  
  48.     The hook will be called with A0 holding the address of your hook
  49.     structure (you may use the h_Data field to your own liking), A2 a
  50.     pointer to the requester structure calling the hook ('req') and A1
  51.     a pointer to an object. The object is variable and depends on what
  52.     your hook is for.
  53.  
  54.     This is an example of a hook suitable to be used with the
  55.     RTFI_FilterFunc tag:
  56.  
  57.     SAS/C users can define their function thus:
  58.  
  59.     BOOL __asm __saveds filterfunc(
  60.             register __a0 struct Hook *filterhook,
  61.             register __a2 struct rtFileRequester *req,
  62.             register __a1 struct FileInfoBlock *fib )
  63.     {
  64.         BOOL accepted = TRUE;
  65.  
  66.         // examine fib to decide if you want this file in the requester 
  67.         ...
  68.         return( accepted );
  69.     }
  70.  
  71.     Your hook structure should then be initialized like this:
  72.  
  73.         filterhook->h_Entry = filterfunc;
  74.         // in this case no need to initialize hook->h_SubEntry
  75.         filterhook->h_Data = your_userdata_if_needed;
  76.  
  77.     You can also use a stub written in machine code to call your
  78.     function. (see 'utility/hooks.h')
  79.    
  80.     INPUTS
  81.     filereq  - pointer to a struct rtFileRequester allocated with
  82.         rtAllocRequestA().
  83.     filename - pointer to an array of chars (must be 108 bytes big).
  84.     title    - pointer to requester window title (null terminated).
  85.     taglist  - pointer to a TagItem array.
  86.  
  87.     TAGS
  88.     RT_Window - see rtEZRequestA()
  89.  
  90.     RT_ReqPos - see rtEZRequestA()
  91.  
  92.     RT_LeftOffset - see rtEZRequestA()
  93.  
  94.     RT_TopOffset - see rtEZRequestA()
  95.  
  96.     RT_PubScrName - see rtEZRequestA()
  97.  
  98.     RT_Screen - see rtEZRequestA()
  99.  
  100.     RT_ReqHandler - see rtEZRequestA()
  101.  
  102.     RT_WaitPointer - see rtEZRequestA()
  103.  
  104.     RT_LockWindow - [V38] see rtEZRequestA()
  105.  
  106.     RT_ScreenToFront - [V38] see rtEZRequestA()
  107.  
  108.     RT_ShareIDCMP - [V38] see rtEZRequestA()
  109.  
  110.     RT_Locale - [V38] see rtEZRequestA()
  111.  
  112.     RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
  113.         this hook for each IDCMP message it gets that doesn't belong to
  114.         its window. Only applies if you used the RT_ShareIDCMP tag to
  115.         share the IDCMP port with the parent window. Parameters are as
  116.         follows:
  117.  
  118.             A0 - (struct Hook *) your hook
  119.             A2 - (struct rtFileRequester *) your requester
  120.             A1 - (struct IntuiMessage *) the message
  121.  
  122.         After you have finished examining the message and your hook
  123.         returns, ReqTools will reply the message. So do not reply the
  124.         message yourself!
  125.  
  126.     RT_Underscore - (char) [V38] Indicates the symbol that precedes the
  127.         character in a gadget's label to be underscored. This will also
  128.         define the keyboard shortcut for this gadget. Currently only
  129.         needed for RTFI_OkText. Usually set to '_'.
  130.  
  131.     RT_DefaultFont - (struct TextFont *) This tag allows you to specify
  132.         the font to be used in the requester when the screen font is
  133.         proportional. Default is GfxBase->DefaultFont. This tag is
  134.         obsolete in ReqTools 2.2 and higher.
  135.  
  136.     RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
  137.         requester. Default is to use the screen font. Note that the
  138.         font must already be opened by you. ReqTools will call
  139.         OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font
  140.         cannot be opened using OpenFont() or if the font is
  141.         proportional the default screen font will be used (or the font
  142.         set with RT_DefaultFont).
  143.  
  144.     RTFI_Flags - (ULONG) Several flags:
  145.  
  146.         FREQF_NOBUFFER - do _not_ use a buffer to remember directory
  147.             contents for the next time the file requester is used.
  148.  
  149.         FREQF_MULTISELECT - allow multiple files to be selected.
  150.             rtFileRequest() will return a pointer to an rtFileList
  151.             structure which will contain all selected files. Use
  152.             rtFreeFileList() to free the memory used by this file list.
  153.  
  154.         FREQF_SELECTDIRS - set this flag if you wish to enable the
  155.             selecting of dirs as well as files. You *must* also set
  156.             FREQF_MULTISELECT. Directories will be returned together
  157.             with files in rtFileList, but with StrLen equal to -1. If
  158.             you need the length of the directory's name use strlen().
  159.  
  160.         FREQF_SAVE - Set this if you are using the requester to save or
  161.             delete something. Double-clicking will be disabled so it is
  162.             harder to make a mistake and select the wrong file. If the
  163.             user enters a non-existent directory in the drawer string
  164.             gadget, a requester will appear asking if the directory
  165.             should be created.
  166.  
  167.         FREQF_NOFILES - Set this if you want to use the requester to
  168.             allow the user to select a directory rather than a file.
  169.             Ideal for getting a destination dir. May be used with
  170.             FREQF_MULTISELECT and FREQF_SELECTDIRS.
  171.  
  172.         FREQF_PATGAD - When this is set a pattern gadget will be added
  173.             to the requester.
  174.  
  175.     RTFI_Height - (ULONG) Suggested height of file requester window.
  176.  
  177.     RTFI_OkText - (char *) Replacement text for "Ok" gadget, max 6
  178.         chars long.
  179.  
  180.     RTFI_VolumeRequest - (ULONG) [V38] The presence of this tag turns
  181.         the file requester into a volume/assign disk requester. This
  182.         requester can be used to get a device name ("DF0:", "DH1:",..)
  183.         or an assign ("C:", "FONTS:",...) from the user. The result of
  184.         this requester can be found in the filereq->Dir field. The
  185.         volume can also be changed with rtChangeReqAttrA() and the
  186.         RTFI_Dir tag. 
  187.  
  188.         Note that the user may edit the disk/assign, or enter a new
  189.         one. Note also that the real device name is returned, not the
  190.         name of the volume in the device. For example "DH1:", not
  191.         "Hard1:". The tag data (ULONG) is used to set following flags:
  192.  
  193.         VREQF_NOASSIGNS - Do not include the assigns in the list, only
  194.             the real devices.
  195.  
  196.         VREQF_NODISKS - Do not include devices, just show the assigns.
  197.  
  198.         VREQF_ALLDISKS - Show _all_ devices. Default behavior is to
  199.             show only those devices which have valid disks inserted
  200.             into them. So if you have no disk in drive DF0: it will not
  201.             show up. Set this flag if you do want these devices
  202.             included.
  203.  
  204.         NOTE: Do *NOT* use { RTFI_VolumeRequest, TRUE }! You are then
  205.             setting the VREQF_NOASSIGNS flag! Use { RTFI_VolumeRequest,
  206.             0 } for a normal volume requester.
  207.  
  208.         NOTE: If you use the RTFI_FilterFunc described below the third
  209.             parameter will be a pointer to a rtVolumeEntry structure
  210.             rather than a pointer to a FileInfoBlock structure! Tech
  211.             note: the DOS device list has been unlocked, so it is safe
  212.             to e.g. Lock() this device and call Info() on this lock.
  213.  
  214.         NOTE: A file requester structure allocated with
  215.             rtAllocRequest() should not be used for both a file and a
  216.             volume requester. Allocate two requester structures if you
  217.             need both a file and a volume requester in your program!
  218.  
  219.     RTFI_FilterFunc - (struct Hook *) [V38] Call this hook for each
  220.         file and directory in the directory being read (or for each
  221.         entry in the volume requester). Parameters are as follows:
  222.  
  223.         A0 - (struct Hook *) your hook
  224.         A2 - (struct rtFileRequester *) your filereq
  225.         A1 - (struct FileInfoBlock *) fib of file OR (struct
  226.             rtVolumeEntry *) device or assign in case of a volume
  227.             requester.
  228.  
  229.         If your hook returns TRUE the file will be accepted. If it
  230.         returns FALSE the file will be skipped and will not appear in
  231.         the requester.
  232.  
  233.         IMPORTANT NOTE: If you change your hook's behavior you _MUST_
  234.             purge the requester's buffer (using rtFreeReqBuffer())!
  235.  
  236.         IMPORTANT NOTE: When this callback hook is called from a volume
  237.             requester the pr_WindowPtr of your process will be set to
  238.             -1 so *no* DOS requesters will appear when an error occurs!
  239.  
  240.     RTFI_AllowEmpty - (BOOL) [V38] If RTFI_AllowEmpty is TRUE an empty
  241.         file string will also be accepted and returned. Defaults to
  242.         FALSE, meaning that if the user enters no filename the
  243.         requester will be canceled. You should use this tag as little
  244.         as possible!
  245.  
  246.     RESULT
  247.     ret - TRUE if the user selected a file (check 'filereq->Dir' for
  248.         the directory and 'filename' for the filename) or FALSE if the
  249.         requester was canceled -- or a pointer to a struct rtFileList
  250.         (if FREQF_MULTISELECT was used).
  251.  
  252.     NOTES
  253.     You CANNOT call the file requester from a task because it uses DOS
  254.     calls!
  255.  
  256.     Automatically adjusts the requester to the screen font.
  257.  
  258.     If the requester got too big for the screen because of a very large
  259.     font, the topaz.font will be used.
  260.  
  261.     rtFileRequest() checks the pr_WindowPtr of your process to find the
  262.     screen to put the requester on.
  263.  
  264.     EXAMPLE
  265.  
  266.     BUGS
  267.     none known
  268.  
  269.     SEE ALSO
  270.  
  271.     INTERNALS
  272.  
  273.     HISTORY
  274.  
  275. ******************************************************************************/
  276. {
  277.     AROS_LIBFUNC_INIT
  278.  
  279.     return FileRequestA((struct RealFileRequester *)filereq, file, title, taglist); /* in filereq.c */
  280.     
  281.     AROS_LIBFUNC_EXIT
  282.     
  283. } /* rtFileRequestA */
  284.